Save API Tool

Used to create or update an API tool that can be used by AI agents. API tools allow agents to interact with external services and APIs to extend their capabilities.

API Endpoint

Property	Value
Request Method	POST
Request URL	https://api.seliseblocks.com/tools/api

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/tools/api' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "tool_weather_api",
    "name": "Weather API",
    "description": "Retrieves current weather information for a given location",
    "base_url": "https://api.weather.com/v1",
    "project_key": "YOUR_PROJECT_KEY"
  }'

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json
Content-Type	application/json	Yes	Data type, must be application/json.

Request Body

Request Body Schema

{
  "id": "string",
  "name": "string",
  "description": "string",
  "base_url": "string",
  "project_key": "string"
}

Request Body Parameters

Field	Type	Required	Description
id	string	No	Unique identifier for the tool. If provided, updates existing tool; otherwise creates new tool.
name	string	Yes	Display name of the API tool.
description	string	Yes	Description of what the API tool does and how it should be used.
base_url	string	Yes	Base URL of the API endpoint.
project_key	string	Yes	The project key for your project.

tip

Creating vs Updating Tools

• Create: Omit the id field or provide a new unique ID to create a new tool
• Update: Provide an existing id to update the tool's configuration

Best Practices

• Use descriptive names that clearly indicate the tool's purpose
• Write detailed descriptions to help the AI understand when and how to use the tool
• Ensure the base URL is accessible and properly formatted
• Include API version in the base URL if applicable

note

Tool Description Guidelines The description field is crucial for helping the AI agent understand:

• What functionality the tool provides
• When it should be used
• What parameters it expects
• What kind of data it returns

Write descriptions that are clear, concise, and include relevant examples or use cases.

Response

Success Response (201 Created)

Returns an object containing the creation/update status and tool details.

{
  "is_success": true,
  "item_id": "tool_weather_api",
  "detail": "API tool created successfully",
  "error": {}
}

Response Fields

Field	Type	Description
is_success	boolean	Indicates whether the operation was successful.
item_id	string	Unique identifier of the created or updated tool.
detail	string	Success or failure message with additional context.
error	object	Error details if the operation failed (empty if successful).

Example Use Cases

// Weather API Tool
{
  "name": "Weather API",
  "description": "Fetches current weather data including temperature, humidity, and conditions for any city worldwide. Use when users ask about weather conditions.",
  "base_url": "https://api.openweathermap.org/data/2.5",
  "project_key": "YOUR_PROJECT_KEY"
}

// CRM Integration Tool
{
  "name": "CRM Customer Lookup",
  "description": "Searches customer records in the CRM system. Returns customer details, order history, and support tickets. Use when users need customer information.",
  "base_url": "https://api.yourcrm.com/v2",
  "project_key": "YOUR_PROJECT_KEY"
}

// Payment Processing Tool
{
  "name": "Payment Gateway",
  "description": "Processes payment transactions and retrieves payment status. Use for payment-related queries and transaction processing.",
  "base_url": "https://api.stripe.com/v1",
  "project_key": "YOUR_PROJECT_KEY"
}

Error Response (422 Unprocessable Entity)

Returns validation error details when the request body is invalid.

{
  "detail": [
    {
      "loc": [
        "body",
        "base_url"
      ],
      "msg": "invalid or missing URL scheme",
      "type": "value_error.url.scheme"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., body field).
msg	string	Human-readable error message.
type	string	Error type identifier.

Error Codes

Status Code	Description	Response Type
201	Created - Tool created/updated successfully	Success
400	Bad Request - Invalid tool configuration	Bad Request
422	Validation Error - Invalid request parameters	Unprocessable Entity
500	Internal Server Error - Operation failed	Server Error

warning

Security Considerations

• Ensure API endpoints are secure and use HTTPS
• Implement proper authentication mechanisms for sensitive APIs
• Validate and sanitize all API responses before using them
• Consider rate limiting to prevent abuse
• Store API keys and credentials securely (not in the tool configuration)
• Monitor tool usage for unusual patterns or potential security issues